WebForm.uploadFileFromBrowser

Displays a special upload page to the user to allow the user to upload one or more files to the server, with UploadOptions to override some of the default parameters. Script processing is suspended when this method is executed and resumes with the next statement when the user clicks either the Upload or Cancel button on the upload page. This method only supports the upload of a single file.

This method can only be called within the context of a web form event. When called from any other context, e.g. a JSP, a RuntimeException is thrown.

Uploaded files are saved on the server in the directory specified in options, or if this is omitted in the directory specified in the Ufs.fileDirectoryName parameter of UFSSetup.properties. The file name on the server is generated from the last portion of the file on the client system with a number added if necessary for uniqueness e.g. the first upload of a file named my_cv.doc will be saved with this name, the second with my_cv1.doc, them my_cv2.doc etc. In addition, any spaces in the file name will be changed to underscores ( _ ) to ensure valid filenames when a Windows file is being saved on a Unix or Linux server. Files can be renamed after upload if necessary using FileServices.moveFile().

Uploaded files can be added as attachments to email messages or used for any other purpose.

The following system variables are set as a result of executing this command (see example below):

• $FILE_NAME is set with the full path name of the uploaded file as saved on the server system. If the Cancel button is pressed by the user, this variable will contain a null value.
• $FILE_NAME_USER is set with the last portion of the file name on the client system e.g. if the user has uploaded C:\My Documents\my_cv.doc, then $FILE_NAME_USER will contain the value my_cv.doc. If the Cancel button is pressed by the user, this variable will contain a null value.

The following options are available (see UploadOptions). If an option is not specified, the corresponding system default from UFSSetup.properties is used.

• specify the target directory on the server (default property Ufs.fileDirectoryName)
• specify the maximum file size that can be uploaded (default property Ufs.maxUploadFileSize)
• specify the file types that can be uploaded (default property Ufs.uploadFileTypes)
• specify the accepted MIME types - used by supporting browsers to constrain the file types shown in the browse panel (no default)

Further documentation.

Javascript example:

 var opts = new UploadOptions();
 opts.directory = "c:/temp";                 // Backslashes should be escaped e.g. c:\\temp
 opts.maxFileSize = "5M";                    // Files larger than 5MB can't be uploaded      
 opts.acceptedMimeTypes = [ "image/*" ];     // Limit the file types shown in the browse panel
 opts.fileTypes = [ "png", "gif", "jpg" ];   // Only these file types can be uploaded
 form.uploadFileFromBrowser(opts);           // Invoke the upload 
 // Processing resumes here after the upload..
 var fname = system.variables.$FILE_NAME.value;
 var fnameUser = system.variables.$FILE_NAME_USER.value;
 if (fname)
 {
      // Show info message if file uploaded successfully
      event.owner.addWarningMessage("File " + fnameUser + " uploaded as " + FileServices.getAbsoluteFilePath(fname));
 }